/**
 * @file		uart.h
 * @brief		UART
 * @note		None
 * @attention	None
 * 
 * <B><I>ALL RIGHTS RESERVED, COPYRIGHT&copy; SOCIONEXT INCORPORATED 2016</I></B>
 */


/** @weakgroup uart_overview
@{
	UART base function.<br>
	Transmission and reception of data by the UART.<br>
	<br>
	Control parameter setting<br>
	- Baud rate : 115200<br>
	- Receive buffer size : 256 byte<br>
	- Send buffer size : 256 byte<br>
	- Auto echo : ON<br>
	- Save to the buffer : Enable<br>
	- UART Mode : Normal<br>
	- Transferring Direction : LSB first<br>
	- Stop bit length : 1 bit<br>
	- Parity bit type : none<br>
	- Data Length : 8 bit length<br>
	- Inversion serial data format : NRZ format<br>
@}*//* --- end of uart_overview */

/** @weakgroup uart_sequence
@{
	- @ref uart_send_sequence
	- @ref uart_receive_sequence
	- @ref uart_sample
	
	@section uart_send_sequence Sequence example of UART Transmission.
	@image html uart_send.png
	<br>
	@section uart_receive_sequence Sequence example of UART Reception.
	@image html uart_receive.png
	<br>

	<hr>
	@section uart_sample Sample code
	The example of UART is as follows.

	@code
	void UART_Send_Sample()
	{
		int ret;
		T_UART_SEND_BUFFER buff;
		
		// set Buffer.
		buff.address = 0xXXXXXXXX;
		buff.size = 10;
		ret = iUARTSetSendBuffer(&buff);
		if (ret != 0) {
			return;
		}
		
		// set notification : enable.
		ret = iUARTSendNotification(1);
		if (ret != 0) {
			return;
		}
		
		// Send start.
		iUARTSendStart();
	}
	
	void UART_Receive_Sample()
	{
		int ret;
		T_UART_RECEIVE_BUFFER buff;
		
		// set Buffer.
		buff.address	= 0xXXXXXXXX;
		buff.size		= 0xFF;
		buff.pointer	= 0xXXXXXXXX;
		buff.overlap	= 0;
		ret = iUARTSetReceiveBuffer(&buff);
		if (ret != 0) {
			return;
		}
		
		// set notification : enable.
		ret = iUARTReceiveNotification(1);
		if (ret != 0) {
			return;
		}
		
		// Receive start.
		ret = iUARTReceiveStart();
		if (ret != 0) {
			iUARTReceiveStop();
			return;
		}
	}
	@endcode

@}*//* --- end of uart_sequence */

#ifndef _UART_H_
#define _UART_H_

/** @weakgroup uart_definition
@{*/

/** Send buffer data */
typedef struct {
	unsigned long		address;		/**< start address of buffer.	*/
	unsigned long		size;			/**< byte size. 0:no-buffer.	*/
} T_UART_SEND_BUFFER;

/** Receive buffer data */
typedef struct {
	unsigned long		address;		/**< start address of buffer.					*/
	unsigned long		size;			/**< byte size. 0:no-buffer.					*/
	unsigned long		pointer;		/**< address of write pointer.					*/
	int					overlap;		/**< 0:no-overlap, 1:cyclic, 2:same position	*/
} T_UART_RECEIVE_BUFFER;

/* @} */	// uart_definition group

/** @weakgroup uart_func
@{*/

/**
UART Init.
*/
extern void vUARTInit(void);

/**
UART Send start.
@retval  0 : success
@retval  1 : patameter error
@retval  3 : function error
*/
extern int iUARTSendStart(void);

/**
UART Receive start.
@retval  0 : success
@retval  2 : status error
*/
extern int iUARTReceiveStart(void);

/**
UART Receive stop.
@retval  0 : success
@retval  2 : status error
*/
extern int iUARTReceiveStop(void);

/**
set UART Send notification.
@param [in]	enable		notification enable.<br>
						0:disable, 1:enable
@retval  0 : success
@retval  1 : parameter error
*/
extern int iUARTSendNotification(int enable);

/**
set UART Receive notification.
@param [in]	enable		notification enable.<br>
						0:disable, 1:enable
@retval  0 : success
@retval  1 : parameter error
*/
extern int iUARTReceiveNotification(int enable);

/**
set UART input buffer for send.
@param [in]	buff		Send buffer data.
@retval  0 : success
@retval  1 : parameter error
*/
extern int iUARTSetSendBuffer(T_UART_SEND_BUFFER const* const buff);

/**
set UART input buffer for receive.
@param [in]	buff		Receive buffer data.
@retval  0 : success
@retval  1 : parameter error
*/
extern int iUARTSetReceiveBuffer(T_UART_RECEIVE_BUFFER const* const buff);

/**
UART Output Terminal.
@param [in]	pointer		send data top.
@param [in]	size		send size.
@retval  0 : success
@retval  1 : failure.
*/
extern int iUARTOutputTerminal(char* pointer, unsigned long size);

/**
Read the input data from the terminal.
@param [out]	pointer		read data top.
@retval  0 : success
@retval  1 : failure.
*/
extern int iUARTReadTerminal(char* pointer);

/* @} */	// uart_func group

#endif	// _UART_H_
